<!doctype html>
<html>
<head>
    <title>agnes API</title>
    <script type="text/javascript" src="agnes.js"></script>
    <link rel="stylesheet" type="text/css" href="agnes.css" />
    <script type='text/javascript'>
        function $(id) {
            return document.getElementById(id);
        }
        function go(example) {
            var code;
            code = $(example).innerHTML.replace(/<br>/mg, '');
            new Function(code)();
        }
    </script>
</head>
<body>
    <img src='logo_r_t_s.png' id='logo' />
    <h1>
        agnes API</h1>
    <p>
        <code>agnes</code> is a mature javascript library for converting between json and
        csv.</p>
    <p>
        Include <code>agnes</code> in your page like this.</p>
    <blockquote>
        <code>&ltscript type="text/javascript" src="agnes.js"&gt;&lt;/script&gt; </code>
    </blockquote>
    <p>
        If you're <em>very</em> clever then you might use a loader or something.</p>
    <p>
        Get <code>agnes</code> here:</p>
    <p>
        <a href='http://agnes.codeplex.com/releases/' class='download'>free source code!</a></p>
    <p>
        She hasn't been minified: I leave that as an exercise for the reader.</p>
    <p>
        Her <a href='tests.html'>unit tests are here</a>, and a <a href='twoWay.html'>demonstration
            of her prowess is here</a>. Her API is described below.</p>
    <p>
        The girl herself is comprised of the following functions, which are documented (with
        executable examples) below.</p>
    <table>
        <thead>
            <tr>
                <th>
                    function
                </th>
                <th>
                    purpose
                </th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>
                    <a href='#csvToJson'>csvToJson</a>
                </td>
                <td>
                    Convert csv into an array of json objects.
                </td>
            </tr>
            <tr>
                <td>
                    <a href='#jsonToCsv'>jsonToCsv</a>
                </td>
                <td>
                    Convert a json object (or json array) into csv.
                </td>
            </tr>
            <tr>
                <td>
                    <a href='#rowDelimiter'>rowDelimiter</a>
                </td>
                <td>
                    Detect the line separator used by the current browser
                </td>
            </tr>
        </tbody>
    </table>
    <h2>
        jargon</h2>
    <p>
        <code>agnes</code> expects you to know these terms:</p>
    <ul>
        <li><em>json</em> - javascript object notation.</li>
        <li><em>csv</em> - comma separated values, but really refers to text separated by any
            form of delimiter.</li>
        <li><em>row</em> - a row of data is sometimes called a line or a record.</li>
        <li><em>field</em> - a field of data is sometimes called a cell or a column.</li>
        <li><em>row delimiter</em> - the character (or string) that separates two rows in csv.
            This is typically a linefeed or a carriage return plus line feed.</li>
        <li><em>field delimiter</em> - the character (or string) that separates two fields in
            csv.</li>
        <li><em>qualifier</em> - if a field contains literal delimiters, the field must be 'qualified',
            i.e. surrounded by qualifiers (i'm doing air quotes here). The qualifier is typically
            a double-quote. If you need to represent the qualifier character literally it is
            doubled (i.e. repeated) inside a qualified field.</li>
    </ul>
    <h2>
        <a name='jsonToCsv'>function: csvToJson</a></h2>
    <blockquote>
        <code>agnes.csvToJson(csvString, rowDelim, fieldDelim) </code>
    </blockquote>
    <p>
        Parameters: <strong>csvString, [rowDelim,] [fieldDelim,] [qualifier]</strong></p>
    <p>
        Converts a piece of separated text into an array of Json objects. Assumes the first
        row of the csv is the name of the properties to create (i.e. assumes the csv includes
        a row of column headers).</p>
    <p>
        Standard escaping rules are applied:</p>
    <ul>
        <li>Qualified fields can contain literal separators.</li>
        <li>A doubled qualifier in a qualified field is treated as a single literal qualifier.
            (Try saying that quickly with your jowls full of boiled sweets)</li>
        <li>Unqualified leading and trailing spaces are trimmed.</li>
        <li>Unqualified empty fields are treated as nulls.</li>
    </ul>
    <p>
        The first parameter, <code>csvString</code>, is the separated text you wish to translate
        into Json.</p>
    <p>
        The last three parameters (rowDelimiter, fieldDelimiter and qualifier) are optional.
        If you don't provide them, <code>agnes</code> is crafty when she works out what
        you want.</p>
    <p>
        If no rowDelimiter is provided she will use whatever the current browser uses as
        a line separator. She performs a little feature detection to make sure she gets
        it right. You can use <code>agnes</code>'s <code>rowDelimiter()</code> function
        to see what delimiter she will use by default on a given browser.</p>
    <p>
        If you don't provide a field delimiter, <code>agnes</code> assumes you want a comma.
        You do want a comma don't you?
    </p>
    <p>
        And for a qualifying character, <code>agnes</code> assumes you want a double-quote.</p>
    </p>
    <h3>
        examples:</h3>
    <blockquote class='example'>
        <code id='examplej1'>var csvData, jsonData;<br />
            csvData = "Name,Age\nJack,12\nJohn,5";<br />
            jsonData = agnes.csvToJson(csvData);<br />
            alert(JSON.stringify(jsonData,null,'  '));</code>
        <input type='button' onclick="go('examplej1');" value="Try it">
    </blockquote>
    <p>
        Or, if you're using custom delimiters, just specify them (row delimiter, then column delimiter)</p>
    <blockquote class='example'>
        <code id='examplej1a'>var myCSV = "Name|Age;Jack|12;John|5;";<br />
            var myJSON = agnes.csvToJson(myCSV, ";", "|");<br />
            alert(JSON.stringify(myJSON,null,'  ')); </code>
        <input type='button' onclick="go('examplej1a');" value="Try it">
    </blockquote>
    <h2>
        <a name='jsonToCsv'>function: jsonToCsv</a></h2>
    <blockquote>
        <code>agnes.jsonToCsv(objects, rowDelim, fieldDelim, qualifier)</code></blockquote>
    <p>
        Parameters: <strong>objects, [rowDelim,] [fieldDelim,] [qualifier]</strong></p>
    <p>
        Converts a json object (or array of json objects) into a separated string. You can
        optionally provide the row delimiter, field delimiter and qualifying character.
        If you omit these parameters, sensible defaults are assumed.</p>
    <p>
        The first parameter can be a single Json object, as in the first example, or an
        array of Json objects, as in the second example. <code>agnes</code> understands.</p>
    <h3>
        examples:</h3>
    <blockquote class='example'>
        <code id='example1'>alert(agnes.jsonToCsv({ "name" : "Mary" }));</code>
        <input type='button' onclick="go('example1');" value="Try it">
    </blockquote>
    <p><code>agnes</code> is not concerned with case sensitivity.</p>
    <blockquote class='example'>
        <code id='example2'>var jsonData, csvData;<br />
            jsonData = [{ "name" : "Mary", "age" : 81, "Occupation": "Seamstress" }, { "Name" : "Alice", "Age" : 403, "Occupation" : "Governess" }];<br />
            csvData = agnes.jsonToCsv(jsonData);<br />
            alert(csvData);</code>
        <input type='button' onclick="go('example2');" value="Try it">
    </blockquote>
    <p>
        Here's an example of using those last three parameters to specify the row delimiter,
        the field delimiter, and how the fields are qualified.</p>
    <blockquote class='example'>
        <code id='example3'>var jsonData, csvData;<br />
            jsonData = [{ "name" : "fred", "age" : 22}];<br />
            csvData = agnes.jsonToCsv(jsonData, "\r\n", "|", '"');<br />
            alert(csvData);</code>
        <input type='button' onclick="go('example3');" value="Try it">
    </blockquote>
    <p>
        If you are sending in an array of Json objects, <code>agnes</code> expects that
        each object has the same properties as the first object, and that those properties are in the same order each time. Furthermore, no property is itself an object. Otherwise <code>agnes</code> will be most perturbed. For example... </p> 

    <blockquote class='example'>
        <code id='example2a'>var jsonData, csvData;<br />
            jsonData = [{ "name" : "Mary",  "age" : 96, "height" : "4ft3", "drunk" : null },<BR />
                        { "name" : "Alice",             "height" : "4ft1",                "ideas" : {"political":"yes", religious: "No!"} }];<br />
            csvData = agnes.jsonToCsv(jsonData);<br />
            alert(csvData);</code>
        <input type='button' onclick="go('example2a');" value="Try it">
    </blockquote>

    <h2>
        <a name='rowDelimiter'>function: rowDelimiter</a></h2>
    <blockquote>
        <code>agnes.rowDelimiter()</code></blockquote>
    <p>
        Determines the standard line ending used on your current browser. Does your current
        browser use just a carriage return? Or does it use a carriage return plus a line
        feed?</p>
    <p>
        Note that <code>agnes</code> does not use old school 'agent' investigation, but the more mature
        approach of 'feature detection' -- making sure she doesn't get tricked into a wrong
        answer.</p>
    <h3>
        example:</h3>
    <p>
        There's not much to show here. Just one example:</p>
    <blockquote class='example'>
        <code id='exampler1'>var delim = agnes.rowDelimiter();<br />
            // in order to show you the invisible characters<br />
            // in the result, i now need to escape it...<br />
            delim = delim.replace("\r","\\r");<br />
            delim = delim.replace("\n","\\n");<br />
            alert("the standard line separator on this browser seems to be... " + delim);
        </code>
        <input type='button' onclick="go('exampler1');" value="Try it">
    </blockquote>
    <p>
        &nbsp;</p>
    <p>
        That's all there is to it.</p>
    <p>
        Have fun.</p>
    <p>
        While you're here, here's a sample for <a href='twoway.html'>converting from Json to CSV and back again.</a>
        &nbsp;</p>
    <p>
        &nbsp;</p>
    <p>
        &nbsp;</p>
    <p>
        &nbsp;</p>
</html>
